[docs] Fix non-public entry docs. Various improvements to PTB docs. by tnowacki · Pull Request #25913 · MystenLabs/sui

tnowacki · 2026-03-20T16:38:21Z

Description

Updated the docs around entry functions.
Fixed missing sections for:
- Move calls
- TxContext
- Publish
- Upgrade

Test plan

👀

Release notes

Check each box that your changes affect. If none of the boxes relate to your changes, release notes aren't required.

For each box you select, include information after the relevant heading that describes the impact of your changes that a user might notice and any actions they must take to implement updates.

vercel · 2026-03-20T16:38:33Z

The latest updates on your projects. Learn more about Vercel for GitHub.

Project	Deployment	Actions	Updated (UTC)
sui-docs	Ready	Preview, Comment	Mar 25, 2026 11:35pm

2 Skipped Deployments

Project	Deployment	Actions	Updated (UTC)
multisig-toolkit	Ignored	Preview	Mar 25, 2026 11:35pm
sui-kiosk	Ignored	Preview	Mar 25, 2026 11:35pm

awelc

Left some suggestions

docs/content/guides/developer/transactions/ptbs/prog-txn-blocks.mdx

awelc · 2026-03-20T17:14:45Z

docs/content/guides/developer/transactions/ptbs/prog-txn-blocks.mdx

+Move calls cannot return references (`&T` or `&mut T`). However, this restriction will be lifted in the future.
+
+**Private generics:**
+Some framework functions have type parameters that can only be instantiated with types defined in the same module. Since PTBs are not modules, they cannot supply these types and therefore cannot call these functions directly. For example, certain `sui::transfer` functions like `transfer` and `share_object` require a type defined in the calling module, and as such cannot be called from a PTB. Instead, use the `public_transfer` and `public_share_object` variants.


Sorry if I am being too picky here, but this suggests that public_transfer and public_share_object will always exist. I realize that they should exist if module developers intended transferring/sharing objects declared in the module but perhaps we could make it more explicit. Maybe finish with something like "Instead, use the public_transfer and public_share_object variants. These should be provided by the module developer."

These are functions in sui::transfer

Aaah, the ones to transfer/share objects with store. The whole thing is more of a nit anyway, but when reading it I thought we are talking objects that actually require module-defined transfer/share functions (and don't have store.

Any thoughts on if I should reword this in any way to be more clear?

docs/content/guides/developer/transactions/ptbs/prog-txn-blocks.mdx

awelc · 2026-03-20T17:23:58Z

docs/content/guides/developer/transactions/ptbs/prog-txn-blocks.mdx

+**Publish:**
+
+- Returns a single `sui::package::UpgradeCap`.
+- After the package is staged, the runtime calls each module's `init` function (if present) in module order. `init` receives `&mut TxContext` and optionally a one-time witness. Additional `init` arguments are not yet supported but are planned.


It's not explicit what "module order" means here

awelc · 2026-03-20T17:27:11Z

docs/content/guides/developer/transactions/ptbs/prog-txn-blocks.mdx

+
+**Cliques**
+
+The system tracks which values are entangled using _cliques_:


I feel like presented in this order, this will be difficult to digest. If possible, I would suggest the following order:

describe intuition (even if it does not cover all the corner cases) behind the entry function rules (in particular, what behavior they try to prevent and which behavior they try to allow)

give some code examples illustrating this

provide a more formal description of the rules via hot cliques

I'm not sure I have a more formal description, but I have tried to expand on the intuition section above and reiterate it here. There are examples in the following section.

docs/content/concepts/sui-move-concepts.mdx

docs/content/guides/developer/transactions/ptbs/inputs-and-results.mdx

docs/content/guides/developer/transactions/ptbs/prog-txn-blocks.mdx

Co-authored-by: Adam Welc <adam@mystenlabs.com> Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com>

damirka · 2026-03-24T13:50:55Z

docs/content/guides/developer/dev-cheat-sheet.mdx

 - If you upgrade a package `P1` to `P2`, other packages and clients that depend on `P1` will continue using `P1`. They do not auto-update to `P2`. Both dependent packages and client code must be explicitly updated to point at `P2`.
 - Packages that expect to be extended by dependent packages can avoid breaking their extensions with each upgrade by providing a standard (unchanging) interface that all versions conform to. See the [message sending](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move) across a bridge example from Wormhole. Extension packages that produce outbound messages can use [`prepare_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L68-L90) from any version of the Wormhole package to produce a [`MessageTicket`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L52-L66) while client code that sends the message must pass that `MessageTicket` into [`publish_message`](https://github.com/wormhole-foundation/wormhole/blob/74dea3bf22f0e27628b432c3e9eac05c85786a99/sui/wormhole/sources/publish_message.move#L92-L152) in the latest version of the package.
-  - `public` function signatures cannot be deleted or changed, but `public(friend)` functions can. Use `public(friend)` or private visibility liberally unless you are exposing library functions that will live forever.
+  - `public` function signatures cannot be deleted or changed, but `public(package)` functions can. Use `public(package)` or private visibility liberally unless you are exposing library functions that will live forever.


damirka · 2026-03-24T13:54:48Z

docs/content/guides/developer/transactions/ptbs/prog-txn-blocks.mdx

+In this invalid PTB, the `HotPotato` from command 0 is still alive in the same clique as `Input(0)` when `spend` is called:
+
+```
+// Invalid PTB


I think it would help visually if we used some syntax on these code blocks. Anything that would grey out comments and make commands stand out.

I will mark them as Move?

Or maybe Rust

docs/content/guides/developer/transactions/ptbs/inputs-and-results.mdx

damirka

LGTM overall with few nits

…ults.mdx Co-authored-by: Damir Shamanaev <damirka.ru@gmail.com>

docs/content/guides/developer/transactions/ptbs/prog-txn-blocks.mdx

jessiemongeon1 · 2026-03-25T22:22:03Z

docs/content/guides/developer/transactions/ptbs/prog-txn-blocks.mdx

+**`TxContext` handling:**
+`TxContext` parameters (`&TxContext` or `&mut TxContext`) are automatically injected by the runtime; callers do not supply them. `TxContext` can appear at any position in the parameter list, and a function can have multiple `TxContext` parameters as long as they are immutable (`&TxContext`). These parameters are not counted toward the user-supplied argument count for indexing purposes.
+
+#### Non-public entry function restrictions {#non-public-entry-function-restrictions}


#non-public-entry-function-restrictions will be the anchor for this heading by default, so you don't need to manually define it, just FYI.

…s.mdx Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com>

tnowacki added 4 commits March 19, 2026 16:53

initial prog

b9a66e9

note

3c694ff

move call

8ab491a

fix docs

8dbff3f

tnowacki requested review from a team, damirka and jessiemongeon1 March 20, 2026 16:38

tnowacki temporarily deployed to sui-typescript-aws-kms-test-env March 20, 2026 16:38 — with GitHub Actions Inactive

github-actions bot added the Type: Documentation Improvements or additions to documentation label Mar 20, 2026

vercel bot deployed to Preview – sui-docs March 20, 2026 16:40 View deployment

awelc reviewed Mar 20, 2026

View reviewed changes

jessiemongeon1 reviewed Mar 23, 2026

View reviewed changes

Apply suggestions from code review

c878b18

Co-authored-by: Adam Welc <adam@mystenlabs.com> Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com>

tnowacki temporarily deployed to sui-typescript-aws-kms-test-env March 24, 2026 02:01 — with GitHub Actions Inactive

vercel bot deployed to Preview – sui-docs March 24, 2026 02:05 View deployment

damirka reviewed Mar 24, 2026

View reviewed changes

docs/content/guides/developer/transactions/ptbs/inputs-and-results.mdx Outdated Show resolved Hide resolved

damirka approved these changes Mar 24, 2026

View reviewed changes

suggestions

4f8288d

tnowacki temporarily deployed to sui-typescript-aws-kms-test-env March 25, 2026 21:31 — with GitHub Actions Inactive

Update docs/content/guides/developer/transactions/ptbs/inputs-and-res…

af0b5b3

…ults.mdx Co-authored-by: Damir Shamanaev <damirka.ru@gmail.com>

tnowacki temporarily deployed to sui-typescript-aws-kms-test-env March 25, 2026 21:31 — with GitHub Actions Inactive

vercel bot deployed to Preview – sui-docs March 25, 2026 21:35 View deployment

jessiemongeon1 approved these changes Mar 25, 2026

View reviewed changes

Update docs/content/guides/developer/transactions/ptbs/prog-txn-block…

281f4ab

…s.mdx Co-authored-by: Jessie Mongeon <133128541+jessiemongeon1@users.noreply.github.com>

tnowacki temporarily deployed to sui-typescript-aws-kms-test-env March 25, 2026 23:29 — with GitHub Actions Inactive

comments

33cff2f

tnowacki temporarily deployed to sui-typescript-aws-kms-test-env March 25, 2026 23:31 — with GitHub Actions Inactive

tnowacki enabled auto-merge (squash) March 25, 2026 23:31

vercel bot deployed to Preview – sui-docs March 25, 2026 23:35 View deployment

tnowacki merged commit 5576006 into MystenLabs:main Mar 25, 2026
55 of 56 checks passed

tnowacki deleted the entry-doc branch March 26, 2026 02:17


		Cliques

		The system tracks which values are entangled using _cliques_:

Conversation

tnowacki commented Mar 20, 2026

Description

Test plan

Release notes

Uh oh!

vercel bot commented Mar 20, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

awelc left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

damirka left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

4 participants

vercel bot commented Mar 20, 2026 •

edited

Loading